PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / basic / lovr.com / LOVR.DOC < prev next >

Wrap

Text File | 1988-10-30 | 22.3 KB | 526 lines

======================= LOVR 1.12 DOCUMENTATION ======================= LICENSE AND WARRANTY -------------------- LOVR copyright 1988 by Michael E. Devore The copyright holder licenses you to use, copy, and distribute LOVR for yourself and others subject to the following four restrictions: 1. LOVR must be copied and distributed only in its original, unmodified form. This includes the LOVR program object module, the LOVR documentation, and all example files. 2. No fee or other compensation can be charged for copying or distributing the program. The only exceptions are user groups and incorporated public domain and shareware software distributors who may charge a handling fee for its distribution NOT TO EXCEED $7.00 PER COPY. ONLY ONE COPY PER COMPUTER DISK IS ALLOWED FOR SUCH DISTRIBUTION. 3. LOVR may NOT be distributed in combination with any other products, software or hardware, without the express written permission of Michael E. Devore. 4. LOVR is for your personal use only and may NOT be used for commercial applications. See the PLOVR program description later in this documentation file if you need to use a version of LOVR commercially. There is no warranty of any kind with LOVR and the copyright holder is not liable for any damages of any kind or nature that may occur due to use of this software. By using LOVR you agree to these terms. Contrapositively, if you do not agree to these terms, do not use LOVR. This document copyright 1988, Michael E. Devore. All rights reserved. ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ LOVR FILES --------- Included in LOVR.ARC should be the following files: LOVR.OBJ (LOVR linkable object module) LOVR.DOC (LOVR documentation file, the file you are reading now) QBNEST.BAS (QuickBASIC 4.0 example files) QBNEST.OBJ . BNEST1.BAS . BNEST1.OBJ . BNEST2.BAS BNEST2.OBJ BNEST3.BAS BNEST3.OBJ BNEST4.BAS BNEST4.OBJ ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ OVERVIEW -------- LOVR is an overlay manager for QuickBASIC. In case this is your first exposure to overlays, the following is a quick overview of what overlay's are, what an overlay manager is, and why such a program is useful. Overlays are portions of program code which are loaded from disk into memory on an as-needed basis. Use of overlays allows an extremely large program (potentially several megabytes of code in size) to execute in a much smaller amount of memory. Code from the program's .EXE file is brought in from disk (overlaid) only when the program needs it. Since all overlays share the same memory space, the memory requirements can be much less than the total code size of the program. Also, there is no longer a need for the clumsy chaining to another file that large QuickBASIC environments frequently require. There is a tradeoff for these advantages. The tradeoff is the time and code overhead necessary to read overlays in from disk. If you make the decision to use overlays with your program, any timing critical code should not be divided between overlays. For most applications, though, the relatively small amount of time it takes to read in an overlay from disk is not important if transfers to overlays are not overdone or poorly timed. Constant shuttling between overlays is an exercise guaranteed to give disappointing results. LINK.EXE, Microsoft's Overlay Linker included with MS-DOS and Microsoft languages, versions 3.x greater than or equal to 3.06, allows creation of overlaid versions of programs. However, LINK only inserts some overlay information and software interrupts in the program for an overlay manager to use. LINK doesn't generate the actual code that loads the proper overlay from disk and passes control to it. That's a job for an overlay manager, and that's where LOVR comes in. LOVR "manages" the overlays. LOVR loads overlays from disk at the appropriate time and jumps program execution to the overlay code. To use LOVR, first compile your QuickBASIC program using the /O option of BC.EXE. LOVR will not work with BRUN40.EXE. Then, link LOVR.OBJ and your program object modules together using Microsoft's Overlay Linker. ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ LOVR SPECIFICATIONS AND REQUIREMENTS ------------------------------------ * LOVR requires an IBM PC or PS/2 microcomputer or close compatible using MS-DOS or PC-DOS operating system version 2.1 or later. Microsoft's Overlay Linker, version 3.06 or later, must be used to link LOVR.OBJ with the object modules of a program containing overlays. * LOVR adds approximately 11K bytes to your program's size when it is linked in. LOVR will also use a maximum of twelve bytes of the overlaid program's stack during its operation. * LOVR has only been tested with QuickBASIC 4.0 programs compiled using the /O option of BC.EXE and linked using Microsoft's Overlay Linker. The object files created by versions of QuickBASIC earlier than 4.0 abort with an error if a link is attempted with overlays. Therefore, LOVR will NOT work with versions of QuickBASIC earlier than 4.0. This is a limitation of the earlier versions of QuickBASIC and not an error or shortcoming in LOVR. * Microsoft's Overlay Linker requires the presence of at least one overlay when linking LOVR.OBJ with a program's object modules. An attempt to link LOVR.OBJ with a program without using at least one overlay will cause LINK to return an "Unresolved externals" error and abort the link. * LOVR will handle a maximum of eight overlays. More than eight overlays will cause LOVR to abort with a "Too many overlays." error. PLOVR, the enhanced version of LOVR, has a limit of 63 overlays -- LINK's maximum. * LOVR supports calls from one overlay to another (nesting). The depth to which overlays can be nested cannot exceed four levels. If an attempt is made to nest deeper than four overlays, LOVR will abort with a "Overlays nested deeper than 4 levels." error. PLOVR supports a nesting depth of 32 levels. * LOVR requires use of the Microsoft LINK default overlay interrupt 63 (3fh). Do not use the /OVERLAYINTERRUPT or /O option of LINK to change the overlay manager interrupt. PLOVR supports changing the default overlay manager interrupt via the /O option of LINK. * LOVR WILL work with the /EXEPACK or /E option of LINK, if the program containing overlays is suitable for using the /EXEPACK option. If the program is not suitable, LINK will abort with a fatal error. The documentation for previous versions of LOVR stating that LOVR and PLOVR would not work with the /EXEPACK option was in error. * After your program has been linked with LOVR.OBJ, do NOT change the program's name. LOVR attempts to load overlays from the executable file name assigned during the linking process. If the file name has been changed, LOVR will abort with a "File not found" error. To change the name of your program, you must relink the program using the new name for your executable file in the link syntax. ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ USING LOVR ---------- To show how to use LINK to set up overlays a set of sample QuickBASIC programs demonstrating the use of LOVR's operations has been included in the LOVR package. Both source and .OBJ files have been included. Although these files perform no useful function, they do demonstrate both overlay nesting and parameter passing to another overlay. Link together the LOVR and QuickBASIC .OBJ files, enclosing in parentheses the modules you want to be overlays. Make sure that you use at least one overlay or LINK will return an unresolved externals error. If you link the example object files together like this: link lovr+qbnest+(bnest1+bnest2+bnest3)+(bnest4),qbnest; a main .EXE file called QBNEST.EXE will be created. This QBNEST.EXE file will contain the root .EXE file QBNEST comprised of the code of the LOVR and QBNEST object modules and will also contain two overlay files appended to the root .EXE file. One overlay file will contain the code of the BNEST1, BNEST2, and BNEST3 modules, the other will contain the code of the BNEST4 module. The .EXE file created is a standard .EXE file. Just type QBNEST at the DOS prompt, and the program will begin to run. As program code is needed from an overlay, that overlay is loaded from disk by the LOVR code if it isn't already loaded, and program execution continues. You may be able to see the program stop running when an overlay is being loaded, depending upon the speed of your disk and whether or not you are using disk caching software. The amount of memory required to load the QBNEST.EXE file you created, or any file created by LINK using overlays, is equal to the size of the root file (including LOVR.OBJ code) plus the size of the largest overlay file plus any program overhead. This brings up an important point. There is no advantage to only using one overlay in a program since space must be allocated for it in memory during program execution anyway. There is only the disadvantage of the overlay overhead. In other words, while the link commands: link lovr+qbnest+(bnest1)+bnest2+bnest3+bnest4,qbnest; link /e lovr+qbnest+(bnest1+bnest2+bnest3+bnest4),qbnest; link lovr+qbnest+bnest1+(bnest2+bnest3)+bnest4,qbnest; are all valid, there is no useful purpose served by linking overlays in this fashion. Two or more overlay files in the link command is the way to go. A more appropriate example of linking using overlays would be: link /exepack lovr+qbnest+(bnest1)+(bnest2)+(bnest4)+bnest3, qbnest; Here there will be three overlay files containing the code of, respectively, BNEST1, BNEST2, and BNEST4, and a root file containing the LOVR, QBNEST and BNEST3 code. Note that the link syntax includes the LINK /EXEPACK option. The /EXEPACK or /E option of Microsoft's Overlay Linker may successfully be used with LOVR.OBJ for those programs suitable for the option. The only overlay combination not allowed by LOVR is one where the LOVR or root (in this case QBNEST) object modules are linked as an overlay. LOVR and QBNEST contain the start up code which must be in loaded in memory during the beginning of the program's execution. To really stretch LOVR to its limits, link each of the BNEST modules in a separate overlay. This forces LOVR to nest overlays to its four level maximum. To use your own QuickBASIC 4.0 programs with overlays you should compile the files using BC.EXE. Overlays will not work with the runtime file BRUN40.EXE so the /O option must be used to compile QuickBASIC 4.0 programs. Feel free to try any permutation of overlays allowed by these examples. LOVR should work with any of them as long as you stay within the restrictions already outlined. It is especially important to remember not to put the initial entry code or LOVR.OBJ in an overlay. The start up code must be in memory when the program is first loaded, i.e. in the root code. You may have noticed that these example files are all small enough to fit into memory without overlays. You may even be asking yourself how you really know that LOVR is bringing the overlays in as needed instead of sneaking everything in at once? In fact, how do you know that LOVR is using the overlay manager interrupt at all? First, you can try running a file linked with overlays without linking in LOVR.OBJ. If you do this your computer will probably lock up and need to be turned off or reset before it can be used again. This is because your program is using interrupt 63 which LOVR hasn't initialized to point to code that manages the overlays. Your program tries to transfer control to whatever random address happens to be at the memory location that corresponds to the address at interrupt 63, leading to unpredictable results. This is also known as a "thin air" transfer. The second test you can do is transfer your overlaid program .EXE file to a floppy disk and disable any disk caching. Now run LOVR off of the floppy disk drive. You should see the floppy disk drive light come on during execution of the example program as overlays are loaded from disk. For maximum effect you may want to link the example program using as many overlays as possible, up to the maximum of eight. It is important to understand how the use of overlays can affect a program's performance. Time critical code should not be divided between two overlays. Depending upon the speed of the disk drive used and the size of the overlay file, the time to load each overlay from disk can be reach several seconds. Extremely time critical code should not be divided the root code and an overlay. The execution time overhead of the overlay manager code can range from several microseconds up to a few milliseconds depending upon the type of machine the overlaid program is running on. There is NO speed penalty involved in calling routines FROM a loaded overlay TO the root code or from one code module to another WITHIN the same overlay file. There IS a speed penalty in calling routines FROM the root code TO an overlay file. This speed penalty will range from several microseconds with an already loaded overlay file on a fast computer to several seconds with an overlay file that needs to be loaded on a computer with a slow disk drive. ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ PLOVR -- An Enhanced Version of LOVR ------------------------------------ If you wish to sell a program that uses LOVR.OBJ to operate, or if you just want a more powerful version of LOVR, an enhanced version of LOVR called PLOVR can be purchased for $45. PLOVR works with any overlay interrupt specified by the /O option of LINK, allows the LINK maximum of 63 overlays, and increases the depth that overlays can be nested to 32 levels. The PLOVR package includes a smaller copy of PLOVR.OBJ called SPLOVR.OBJ, which takes up 5K of program space in the root code, instead of 11K. The trade-off is an occasional increase in time to load an overlay from disk, but SPLOVR can be useful for those running close to the memory space limit even with overlays. PLOVR also dispenses with the runtime copyright notice. This removal of the runtime copyright notice does not suggest, and should not be taken to suggest, that PLOVR is not copyrighted. A potentially distracting message is simply not displayed. No royalties are charged for use of PLOVR. This means that you need only purchase a single version of PLOVR for use with your program no matter how many copies of your program you distribute. Purchase of PLOVR entitles the purchaser to telephone support. All calls will be at the purchaser's expense. Note that purchase of PLOVR is MANDATORY if you wish to use a version of LOVR for distribution with a commercial or shareware program. PLOVR is the only version of the overlay manager permitted for use with such applications. To purchase PLOVR send $45.00, in US dollars, by check or money order with your shipping address to: Michael E. Devore Devore Software & Consulting 403 West Charles Champaign, IL 61820 Please state your preference for either 5 1/4 or 3 1/2 inch diskettes. All information contained herein, including the cost of PLOVR, is subject to change without notice. PLOVR copyright 1988 by Michael E. Devore ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ TROUBLE-SHOOTING ---------------- Check to make sure that you have compiled your program properly. You should compile your source files outside of the QuickBASIC integrated environment with BC.EXE using the /O option. Use a recent version of Microsoft's Overlay Linker when linking overlays for LOVR. LOVR was tested with Microsoft LINK versions 3.06, 3.60, 3.61 and 3.64. 2.x versions of LINK will not work. The copyright notice of LINK must say Microsoft Overlay Linker, Turbo C's TLINK or other proprietary linkers will not work with LOVR. In addition, if you experience problems with LOVR, try linking with a different version of Microsoft's Overlay Linker -- at least one version of the linker has an error that causes improper overlay operation. Check your link syntax, making sure that neither LOVR nor the initial entry or main program module is in an overlay, and that you are not exceeding eight overlay files or nesting overlays deeper than four levels. If you are sure that you are compiling and linking properly and operating LOVR within its specifications and requirements, make sure that the error is not in your program. If memory size allows, compile your program without overlays and test it. If the size of your program is too large for all of it to fit in memory, try to compile only the code that is giving you problems and see if it works correctly without overlays. If your program still fails after you have eliminated all suspects except for LOVR, please contact me so I can fix the problem as soon as possible. In order to facilitate locating the problem, I will need some background information. What error message, if any, does LOVR print? What version and options of LINK were used? What hardware and software configuration was your machine running under when the error occurred? What language was the program written in? If an error is in LOVR and you are the first person to find the error, I will send you a free corrected version as soon as it is available. The corrected version will either be sent by electronic mail if possible, or regular USPS mail if not. If you are not the first person to find the error and do not wish to wait for the corrected version to reach general distribution channels, you may send $6.00 to cover shipping and handling for the latest version to the address below. If you subscribe to either the CompuServe Information Service, the GEnie Information Service, or the Byte Information Exchange, you can send me electronic mail at the appropriate e-mail address below. I check in to the CIS and GEnie services at least once a week -- usually more frequently -- and BIX at least twice a month. Your e-mail will be acknowledged as soon as I receive it. If you do not subscribe to either CompuServe, GEnie, or BIX you should contact me through USPS mail at the address below: MAILING ADDRESS: Michael E. Devore Devore Software & Consulting 403 West Charles Champaign, IL 61820 E-MAIL ADDRESSES: CompuServe 71540,62 GEnie MDEVORE BIX mdevore ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ COMMENTS AND SUGGESTIONS ------------------------ If you have an idea for an improvement to LOVR, a comment or question about LOVR, or even a complaint about LOVR, please send it to either my USPS mailing address or one of the e-mail addresses below. I am receptive to new ideas and constructive criticism. Don't be shy, feedback oftens leads to improvements benefiting everyone. LOVR began life as an offshoot of OVL, a non-linkable shell-type overlay manager I wrote that has several bells and whistles, including user-defineable, multiple overlay areas and multi-language capability. LOVR has fewer options, but it can be linked in with QuickBASIC programs, resulting in one clean .EXE file. Several people indicated a willingness to take the options versus one .EXE file trade-off, and thus LOVR was born. If you wish a copy of OVL and you have been unsuccessful in obtaining a copy, you may send $6.00 to cover shipping and handling for the latest version to the USPS address below. Michael E. Devore Devore Software & Consulting 403 West Charles Champaign, IL 61820 CompuServe 71540,62 GEnie MDEVORE BIX mdevore ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of The Public (Software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. The P(s)L cannot de- bug programs over the telephone. Disks in the P(s)L are updated monthly, so if you did not get this disk directly from the P(s)L, you should be aware that the files in this set may no longer be the current versions. For a copy of the latest monthly software library newsletter and a list of the 1,400+ disks in the library, call or write The Public (Software) Library P.O.Box 35705 - F Houston, TX 77235-5705 (713) 665-7017